<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
        "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xml:lang="en" xmlns="http://www.w3.org/1999/xhtml">
<head>
  <title>areaDetector Plugin NDPluginScatter</title>
  <meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type" />
</head>
<body>
  <div style="text-align: center">
    <h1>
      areaDetector Plugin NDPluginScatter</h1>
    <h2>
      March 4, 2017</h2>
    <h2>
      Mark Rivers</h2>
    <h2>
      University of Chicago</h2>
  </div>
  <h2>
    Contents</h2>
  <ul>
    <li><a href="#Overview">Overview</a></li>
    <li><a href="#Configuration">Configuration</a></li>
    <li><a href="#Screens">Screen shots</a></li>
  </ul>
  <h2 id="Overview">
    Overview
  </h2>
  <p>
    This plugin is used to distribute (scatter) the processing of NDArrays to multiple
    downstream plugins. It allows multiple intances of a plugin to process NDArrays
    in parallel, utilizing multiple cores to increase throughput. It is commonly used
    in together with <a href="NDPluginGather.html">NDPluginGather</a>, which gathers
    the outputs from multiple plugins back into a single stream. The <a href="NDPluginGather.html">
      documentation for NDPluginGather</a> provides a detailed example of using NDPluginScatter
    and NDPluginGather to do parallel processing of 5 statistics plugins.
  </p>
  <p>
    This plugin works differently from other plugins that do callbacks to downstream
    plugins. Other plugins pass each NDArray that they generate of <b>all</b> downstream
    plugins that have registered for callbacks. NDPluginScatter does not do this, rather
    it passes each NDArray to only one downstream plugin. The mechanism for chosing
    which plugin to pass the next NDArray to can be described as a modified round-robin.
    The first NDArray is passed to the first registered callback client, the second
    NDArray to the second client, etc. After the last client the next NDArray goes to
    the first client, and so on. The modification to strict round-robin is that if client
    N input queue is full then an attempt is made to send the NDArray to client N+1,
    and if this would fail to client N+2, etc. If no clients are able to accept the
    NDArray because their queues are full then the last client that is tried (N-1) will
    drop the NDArray. Because the "last client" rotates according the round-robin schedule
    the load of dropped arrays will be uniform if all clients are executing at the same
    speed and if their queues are the same size.</p>
  <p>
    Their is an NDPluginScatterMethod parameter in the driver to allow future implementations
    of other scheduling schemes, should this prove desireable.</p>
  <p>
    NDPluginScatter inherits from NDPluginDriver. NDPluginScatter does not do any modification
    to the NDArrays that it receives except for possibly adding new NDAttributes if
    an attribute file is specified. The <a href="areaDetectorDoxygenHTML/class_n_d_plugin_scatter.html">
      NDPluginScatter class documentation</a> describes this class in detail.</p>
  <h2 id="Configuration">
    Configuration</h2>
  <p>
    The NDPluginScatter plugin is created with the NDScatterConfigure command, either
    from C/C++ or from the EPICS IOC shell.</p>
  <pre>NDScatterConfigure (const char *portName, int queueSize, int blockingCallbacks, 
                      const char *NDArrayPort, int NDArrayAddr, size_t maxMemory, 
                      int priority, int stackSize)
  </pre>
  <p>
    For details on the meaning of the parameters to this function refer to the detailed
    documentation on the NDScatterConfigure function in the <a href="areaDetectorDoxygenHTML/_n_d_plugin_scatter_8cpp.html">
      NDPluginScatter.cpp documentation</a> and in the documentation for the constructor
    for the <a href="areaDetectorDoxygenHTML/class_n_d_plugin_scatter.html">NDPluginScatter
      class</a>.
  </p>
  <h2 id="Screens">
    Screen shots</h2>
  <p>
    The following is the MEDM screen that provides control of the NDNDPluginScatter
    plugin. Note that it currently only contains the controls for the base class NDPluginDriver.
  </p>
  <div style="text-align: center">
    <h3>
      NDScatter.adl</h3>
    <p>
      <img alt="NDScatter.png" src="NDScatter.png" /></p>
  </div>
</body>
</html>
